Add toplevel docs for the sidebar

Signed-off-by: Federico Mena Quintero <federico@gnome.org>

diff --git a/gtk/gtkfilechooser.c b/gtk/gtkfilechooser.c
index df794e2ae1e3d23183d4737118d0c9b3f6cfda51..c1d302577c1c509654312453e0848928bf6d1631 100644 (file)
--- a/gtk/gtkfilechooser.c
+++ b/gtk/gtkfilechooser.c
@@ -55,9 +55,8 @@
  *    <varlistentry>
  *       <term>Shortcuts</term>
  *       <listitem>
- *          can be provided by the application or by the underlying filesystem
- *          abstraction (e.g. both the gnome-vfs and the Windows filesystems
- *          provide "Desktop" shortcuts). Shortcuts cannot be modified by the
+ *          can be provided by the application.  For example, a Paint program may
+ *          want to add a shortcut for a Clipart folder.  Shortcuts cannot be modified by the
  *          user.
  *       </listitem>
  *    </varlistentry>

diff --git a/gtk/gtkplacessidebar.c b/gtk/gtkplacessidebar.c
index 3b13d9ef7bf1d64e8b1d57e46ae362982ce60cb3..4b9e814c75814b4390f0f26688c282b3c441d2e7 100644 (file)
--- a/gtk/gtkplacessidebar.c
+++ b/gtk/gtkplacessidebar.c
@@ -87,6 +87,36 @@
 #include "gtktypebuiltins.h"
 #include "gtkwindow.h"
 
+/**
+ * SECTION:gtkplacessidebar
+ * @Short_description: Sidebar that displays frequently-used places in the file system
+ * @Title: GtkPlacesSidebar
+ * @See_also: #GtkFileChooser
+ *
+ * #GtkPlacesSidebar is a widget that displays a list of frequently-used places in the
+ * file system:  the user's home directory, the user's bookmarks, and volumes and drives.
+ * This widget is used as a sidebar in #GtkFileChooser and may be used by file managers
+ * and similar programs.
+ *
+ * The places sidebar displays drives and volumes, and will automatically mount
+ * or unmount them when the user selects them.
+ *
+ * Applications can hook to various signals in the places sidebar to customize
+ * its behavior.  For example, they can add extra commands to the context menu
+ * of the sidebar.
+ *
+ * While bookmarks are completely in control of the user, the places sidebar also
+ * allows individual applications to provide extra shortcut folders that are unique
+ * to each application.  For example, a Paint program may want to add a shortcut
+ * for a Clipart folder.
+ *
+ * To make use of the places sidebar, an application at least needs to connect
+ * to the #GtkPlacesSidebar::open-location signal.  This is emitted when the
+ * user selects in the sidebar a location to open.  The application should also
+ * call gtk_places_sidebar_set_location() when it changes the currently-viewed
+ * location.
+ */
+
 #define EJECT_BUTTON_XPAD 6
 #define ICON_CELL_XPAD 6